Claude Code 高级技巧与组件架构完全指南

版本: Claude Code 2.x | 更新: 2026-04-30 涵盖: 架构组件、高级工作流、上下文管理、多Agent协作、Skills/Hooks/MCP 系统

架构总览

整体架构图

┌─────────────────────────────────────────────────────────────┐
│                       Claude Code CLI                        │
├─────────────────────────────────────────────────────────────┤
│  CLI Interface (claude)                                      │
│  ├─ REPL Mode (交互式对话)                                    │
│  ├─ Print Mode (claude -p "prompt")                          │
│  └─ File Mode (claude -f input.txt)                          │
├─────────────────────────────────────────────────────────────┤
│                     Core Engine Layer                         │
│  ├─ Session Manager (会话管理、历史压缩)                        │
│  ├─ Prompt Composer (系统提示组装、上下文注入)                    │
│  ├─ Tool Registry (工具注册、权限调度)                           │
│  └─ Model Router (模型选择、回退策略)                            │
├─────────────────────────────────────────────────────────────┤
│                    Extension Layer                            │
│  ├─ Skills System (领域专业化指令)                              │
│  ├─ Hooks System (事件驱动的生命周期钩子)                         │
│  ├─ MCP Client (Model Context Protocol)                       │
│  ├─ Plugin System (插件市场集成)                                │
│  └─ Sub-Agent System (子Agent编排)                             │
├─────────────────────────────────────────────────────────────┤
│                    Integration Layer                          │
│  ├─ Anthropic API (Messages API / Streaming)                  │
│  ├─ File System (工作区读写)                                   │
│  ├─ Terminal (Bash/Shell执行)                                 │
│  └─ Git Integration (版本控制操作)                             │
└─────────────────────────────────────────────────────────────┘

关键设计原则

原则	说明
工具优先	AI通过标准化工具接口与环境交互，而非自由文本响应
权限最小化	所有危险操作需用户批准，支持分层权限配置
上下文隔离	子Agent独立上下文，防止污染主会话
声明式配置	CLAUDE.md、settings.json、mcp.json 声明式管理行为
事件驱动扩展	Hooks在生命周期节点注入自定义逻辑

核心组件详解

1. Session Manager (会话管理器)

会话管理器负责维护对话状态、历史压缩和上下文预算控制。

会话生命周期:
  启动 → 加载CLAUDE.md → 注入Evolution Memory → 加载Skills
    → 创建System Prompt → 开始对话 → [压缩] → 结束

关键行为:

自动压缩: 当上下文接近模型限制时自动触发，压缩策略保留关键决策和代码上下文
会话恢复: claude --resume 或 claude --continue
上下文隔离: 每个会话独立，/clear 清除历史但仍保留项目级配置

会话文件位置:

~/.claude/projects/<project-hash>/     # 项目级会话数据
~/.claude/sessions/                    # 会话记录

2. Prompt Composer (提示词组装器)

系统提示由多层组件组装而成，遵循优先级链:

层级结构 (优先级从高到低):
  1. User Prompt (用户当前消息)           ← 最高优先级
  2. CLAUDE.md (项目级指令)               ← 始终生效
  3. Skills 注入 (匹配的技能指令)          ← 条件生效
  4. Hooks 注入 (钩子附加指令)            ← 事件驱动
  5. MCP Tool Descriptions (工具描述)     ← 按需加载
  6. System Guardrails (内置安全护栏)     ← 始终生效
  7. Base System Prompt (基础系统提示)    ← 始终生效

系统提示来源:

内置系统提示: Claude Code 内置的行为指令 (~4000 tokens)
CLAUDE.md: 项目根目录或递归上级目录的指令文件
Skills: 技能文档中的系统指令段
MCP: 各服务器提供的工具描述
Hooks 额外指令: 通过钩子注入的动态指令

3. Tool Registry (工具注册表)

Claude Code 通过统一的工具接口与外部交互:

工具类别	核心工具	权限级别
文件操作	Read, Write, Edit, Glob, Grep	默认允许(只读) / 需批准(写入)
终端执行	Bash	需批准(默认), 可配置白名单
任务编排	Task, TaskOutput, TaskList	自动(内部调用)
Web访问	WebSearch, WebFetch	需网络权限
用户交互	AskUserQuestion	自动
会话控制	ExitPlanMode, EnterPlanMode	自动

工具权限配置 (settings.json):

json

{
  "permissions": {
    "allow": [
      "Bash(git:*)",
      "Bash(npm:*)",
      "Bash(node:*)",
      "Read",
      "Write"
    ],
    "deny": [
      "Bash(curl:*)",
      "Bash(rm -rf:*)"
    ],
    "ask": [
      "Bash(docker:*)",
      "Bash(python:*)"
    ]
  }
}

4. Model Router (模型路由器)

Claude Code 支持多模型切换和智能路由:

模型选择逻辑:
  默认: Sonnet (均衡性能/成本)
  Plan Mode: 自动使用最强的可用模型
  子Agent:
    ├─ 机械任务 → Haiku (快速/低成本)
    ├─ 集成任务 → Sonnet (均衡)
    └─ 架构设计 → Opus (深度推理)

模型切换方式:

bash

claude --model opus                  # 启动时指定模型
/model opus                          # 会话内切换 (REPL命令)
/model haiku                         # 切换至Haiku

子Agent系统

架构设计

子Agent系统是Claude Code最具影响力的高级特性之一，支持将复杂任务分解为独立的并行执行单元。

主会话 (Main Claude)
  │
  ├─ Task("explore-codebase") ─── Explore Agent ──→ 研究结果
  ├─ Task("implement-feature-A") ─ Plan Agent ──→ 实现计划
  ├─ Task("fix-bug-B") ──────── Bash Agent ──→ 修复提交
  └─ Task("code-review") ───── General Agent ──→ 审阅报告

Agent类型全览

Agent类型	可用工具	适用场景	推荐模型
Explore	全部(除Edit/Write/Task)	代码库探索、搜索、架构理解	Haiku
Plan	全部(除Edit/Write/Task)	设计实现方案、架构决策	Opus
Bash	仅Bash	命令行操作、Git、构建	Haiku
General-Purpose	全部工具	复杂多步骤任务	Sonnet
statusline-setup	Read, Edit	配置状态栏	Haiku
claude-code-guide	Glob, Grep, Read, WebFetch/Search	回答Claude Code相关问题	Haiku

并行Agent派发模式

何时使用并行派发:

3+个测试失败且根因各自独立
多个互不依赖的子系统同时出问题
每个问题不需要其他Agent的上下文

并行派发示例:

场景: 三个独立功能需要同时实现

不推荐 (串行):
  Task → 等结果 → Task → 等结果 → Task

推荐 (并行):
  Task(功能A) ┐
  Task(功能B) ├── 同时启动, 互不干扰
  Task(功能C) ┘

Agent任务描述最佳实践:

好的任务描述包含:
  ✅ 明确的输入/输出约定
  ✅ 具体的成功标准
  ✅ 不能修改的文件列表 (如果适用)
  ✅ 必须遵循的约束条件
  ✅ 输出格式要求

坏的任务描述:
  ❌ "帮我修复这个bug" (太模糊)
  ❌ "优化代码" (没有具体目标)

后台Agent模式

长任务可以放到后台执行，不阻塞主会话:

python

# 在对话中使用
"请用后台模式运行这个构建任务"

# Agent会返回 output_file 路径
# 使用 TaskOutput 检查进度
TaskOutput(task_id="xxx", block=false)

子Agent上下文管理

关键原则: 子Agent间绝不共享上下文

原因:
  1. 上下文隔离防止错误的假设传播
  2. 独立的思考过程避免群体思维
  3. 清晰的责任边界便于验证

实现:
  - 每个Task调用启动一个全新的Agent
  - Agent拥有独立的工具实例
  - 结果通过返回值传递 (而非共享状态)

Skills技能系统

技能架构

技能系统是Claude Code最核心的扩展机制，通过专用的指令文档在特定场景下激活:

技能加载流程:
  用户指令 → 关键词匹配 → 触发条件检查
    → 加载技能文档 → 注入系统提示 → 执行

技能存储位置:
  ~/.agents/skills/          # 所有已安装技能
  ~/.claude/skills/          # 激活的技能(符号链接)
  ~/.agents/.skill-lock.json # 技能注册表

技能三大类型

类型	说明	行为
刚性技能 (Rigid)	必须严格遵循	TDD: 未写测试绝不能写实现代码
灵活技能 (Flexible)	适配原则到场景	Patterns: 模式可因地制宜调整
参考技能 (Reference)	按需查阅	API Docs: 需要时查看, 不主动注入

技能优先级

技能冲突时的优先级:
  1. 用户显式指定 > 2. Superpowers > 3. 项目CLAUDE.md >
  4. 流程技能 > 5. 实现技能 > 6. 参考技能

Superpowers (始终最高优先级):
  brainstorming, systematic-debugging,
  test-driven-development, verification-before-completion

技能管理命令

bash

# 发现搜索技能
pnpm dlx skills find "关键词"

# 安装技能
pnpm dlx skills add <源> -s <技能名> -a claude-code -y

# 列出并管理
pnpm dlx skills list
pnpm dlx skills update
pnpm dlx skills remove <技能名>

# 技能审计
# 使用 skill-stocktake: 分析冗余
# 使用 rules-distill: 去重合并

自定义技能开发

markdown

# 技能文档模板 (SKILL.md)

## 触发条件
- 关键词: "xxx", "yyy"
- 场景: 创建Vue组件时

## 系统指令
- 注册到系统提示的专用指令

## 规则
1. 必须遵守的规则
2. 推荐遵循的模式

## 示例
- 正面示例: 正确的做法
- 反面示例: 错误的反模式

Hooks钩子系统

Hooks架构

Hooks允许在Claude Code的生命周期节点注入自定义行为:

事件生命周期:
  SessionStart ──→ PreToolUse ──→ PostToolUse ──→ SessionEnd
                  (每个工具调用前后触发)

  附加事件:
  Notification (对话通知)
  Stop (对话结束)
  SubagentStop (子Agent结束)

Hook配置

全局配置:

json

// ~/.claude/settings.json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "command": "echo 'About to run: $CLAUDE_TOOL_INPUT' >> ~/.claude/audit.log"
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "npx prettier --write $CLAUDE_FILE_PATH"
      }
    ],
    "SessionStart": [
      {
        "command": "echo Session started at $(date) >> ~/.claude/session.log"
      }
    ]
  }
}

Hooks环境变量

变量	说明	可用事件
`CLAUDE_TOOL_NAME`	被调用的工具名	PreToolUse, PostToolUse
`CLAUDE_TOOL_INPUT`	工具输入参数	PreToolUse, PostToolUse
`CLAUDE_FILE_PATH`	被操作的文件路径	PostToolUse (Write/Edit)
`CLAUDE_TOOL_OUTPUT`	工具输出结果	PostToolUse
`CLAUDE_SESSION_ID`	当前会话ID	所有事件

Hooks常见应用场景

安全性:  PreToolUse 拦截危险命令 (rm -rf, curl 未授权地址)
格式化:  PostToolUse 自动运行 linter/formatter
审计:   PostToolUse 记录所有文件变更
监控:   SessionStart/End 统计使用时长
自动化: PostToolUse 自动重新加载开发服务器

Evolution Memory (Evolver)

Evolver 是一个特殊的Hooks实现，用于自我进化:

Evolver 工作流:
  Session Start → 注入历史进化记忆
  File Edit     → 检测进化信号
    ├─ log_error
    ├─ perf_bottleneck
    ├─ user_feature_request
    ├─ capability_gap
    ├─ deployment_issue
    └─ test_failure
  Session End   → 记录进化结果

MCP协议集成

MCP架构

Model Context Protocol (MCP) 允许Claude Code接入外部工具和数据源:

Claude Code (MCP Client)
    │
    ├─ stdio ────→ MCP Server A (本地进程通信)
    │              ├─ Tool: search_docs
    │              └─ Resource: file://docs/api.md
    │
    └─ HTTP ────→ MCP Server B (远程服务器)
                   ├─ Tool: query_database
                   └─ Resource: postgres://analytics

MCP配置 (mcp.json)

json

{
  "mcpServers":***@modelcontextprotocol/server-filesystem", "/path/to/data"],
      "type": "stdio",
      "env": {
        "API_KEY": "${ENV_VAR}"
      }
    },
    "remote-api": {
      "url": "https://api.example.com/mcp",
      "type": "streamableHttp",
      "headers": {
        "Authorization": "Bearer ${TOKEN}"
      }
    }
  }
}

MCP上下文预算影响

关键洞察: MCP是上下文预算的最大消耗者

每个MCP工具 ≈ 500 tokens (schema + description)
30个工具的MCP服务器 ≈ 15,000 tokens

优化策略:
  ✅ 只启用当前会话需要的MCP服务器
  ✅ 工具description保持精简
  ✅ 使用项目级mcp.json而非全局
  ❌ 不要同时启用所有MCP服务器

MCP服务器安全

MCP安全审计清单:
  □ 服务器来源可信
  □ 命令行参数无注入风险
  □ 环境变量不暴露密钥
  □ 工具权限与预期一致
  □ 网络访问范围可控

扫描命令:
  npx ecc-agentshield scan

上下文窗口管理

上下文组成结构

┌─────────────────────────────────────────┐
│  System Prompt (~4000 tokens)           │ 固定开销
│  ├─ Base instructions                    │
│  └─ Tool descriptions                    │
├─────────────────────────────────────────┤
│  Project Context (~2000-8000 tokens)    │ 项目级
│  ├─ CLAUDE.md                            │
│  ├─ Active Skills ($SKILL.md)            │
│  └─ MCP tool schemas                     │
├─────────────────────────────────────────┤
│  Conversation History (动态)            │ 会话级
│  ├─ Messages                             │
│  ├─ Tool calls & results                 │
│  └─ File contents                        │
├─────────────────────────────────────────┤
│  Available Budget (剩余空间)            │ 可变
└─────────────────────────────────────────┘

上下文优化策略

策略1: 精简CLAUDE.md
  ✅ 只写真正需要的指令
  ✅ 使用外部引用 (~/.claude/agents/ 下的独立文件)
  ❌ 不要把所有规则堆在一个文件

策略2: 合理安排Skills
  ✅ 使用 项目级CLAUDE.md 引用技能
  ❌ 不要全局激活所有技能

策略3: MCP按需启用
  ✅ 项目级 mcp.json 只包含相关服务器
  ❌ 全局 mcp.json 不要加载所有内容

策略4: 及时压缩会话
  /compact         # 手动触发压缩
  # 自动压缩发生在上下文接近限制时

Token预算感知

Claude Code 内置了token budget感知，当你接近上下文极限时:

自动触发 --thinking 中的决策
提示进行会话压缩
建议切换到更长的上下文窗口模式

工具系统深度解析

Task 工具 (子Agent编排)

typescript

// Task工具参数结构
Task({
  description: "简短描述 (3-5词)",      // 必填
  prompt: "详细任务描述",                // 必填
  subagent_type: "general-purpose",     // 必填: Agent类型
  model: "haiku",                       // 可选: 模型选择
  resume: "agent-id",                   // 可选: 恢复之前的Agent
  run_in_background: true,              // 可选: 后台运行
  max_turns: 50                         // 可选: 最大轮次
})

Bash 工具 (终端执行)

安全机制:
  1. 命令发送前预检 (基于permissions配置)
  2. 危险命令列表匹配 (rm -rf, sudo, chmod 777等)
  3. 沙箱执行 (可选)
  4. 输出截断 (超过30K字符自动截断)
  5. 超时控制 (默认120s, 最大600s)

最佳实践:
  ✅ 使用绝对路径
  ✅ 拆分长串行命令 (用&&而非;)
  ❌ 不要在Bash工具中做文件操作 (用Read/Write/Edit)

文件操作工具

Read:    读取文件 (支持PDF、图片、Jupyter Notebook)
Write:   创建/覆盖文件
Edit:    精确字符串替换 (不破坏文件其余部分)
Glob:    文件名模式匹配
Grep:    内容正则搜索 (支持多行)

原则: Read Only → Edit (优先) → Write (最后手段)

CLI命令与高级配置

命令总览

bash

# 基础命令
claude                           # 启动交互式REPL
claude "问题描述"                 # 单次查询
claude -p "prompt"               # Print模式 (输出到stdout)
claude -f prompt.txt             # 从文件读取prompt
claude --pipe                    # 从stdin读取

# 会话管理
claude --continue / --resume     # 恢复上次会话
claude --resume <session-id>     # 恢复指定会话
/clear                           # 清除当前对话历史
/compact                         # 压缩会话上下文

# 模型控制
claude --model opus              # 指定模型启动
claude --model sonnet
/model haiku                     # 会话内切换 (REPL命令)

# 输出控制
claude -p --output-format json   # JSON输出
claude -p --output-format stream-json  # 流式JSON
claude -p --max-turns 20         # 限制最大轮次

# 权限控制
claude --allowedTools "Bash,Read"  # 限制可用工具
claude --permission-mode acceptEdits  # 自动接受编辑

# 调试
claude --debug                   # 调试模式
claude --verbose                 # 详细日志

# IDE模式
claude --ide                     # IDE集成模式

# 配置
claude config                    # 交互式配置
claude update                    # 自动更新

高级REPL命令

/help            # 帮助信息
/clear           # 清除对话
/compact         # 压缩会话
/model <name>    # 切换模型
/theme <name>    # 切换主题
/memory          # 编辑项目记忆
/context         # 显示上下文使用情况
/statusline      # 配置状态栏
/doctor          # 诊断环境问题
/tasks           # 查看任务列表
/plugin          # 插件管理
/cost            # 查看API费用
/export          # 导出会话

settings.json 完整配置参考

json

{
  "model": "sonnet",
  "permissions": {
    "allow": [],
    "deny": [],
    "ask": ["Bash:*"],
    "defaultMode": "default"
  },
  "enableExtendedThinking": true,
  "hooks": {
    "PreToolUse": [],
    "PostToolUse": [],
    "Notification": [],
    "SessionStart": [],
    "SessionEnd": []
  },
  "statusLine": {
    "type": "model",
    "showCost": true
  },
  "theme": "system",
  "enablePromptCaching": true,
  "projectOnboarding": true,
  "mcpServers": {},
  "env": {},
  "ignorePatterns": [
    ".git/",
    "node_modules/",
    "__pycache__/"
  ]
}

高级工作流模式

Plan Mode (计划模式)

何时使用Plan Mode:
  ✅ 新建功能 (多文件、架构决策)
  ✅ 重构 (影响范围大)
  ✅ 性能优化 (多种策略可选)
  ✅ 技术选型 (需要权衡)

Plan Mode工作流:
  1. EnterPlanMode → 深入代码库探索
  2. 分析现有架构和约束
  3. 设计多个方案 (包含权衡分析)
  4. 写出详细计划 (文件级变更)
  5. ExitPlanMode → 用户审阅
  6. 批准后按计划逐步骤实现

Subagent-Driven Development (子Agent驱动开发)

完整流程:
  1. brainstorming (设计, 产出: 设计文档)
  2. writing-plans (写计划, 产出: 任务拆解)
  3. subagent-driven-development (执行)
     ├─ Task 1 → Code Review → 修复 → 合并
     ├─ Task 2 → Code Review → 修复 → 合并
     └─ Task 3 → Code Review → 修复 → 合并
  4. verification-before-completion (验证)
  5. finishing-a-development-branch (收尾)

关键特点:
  - 每个任务用全新子Agent (隔离上下文)
  - 两阶段审阅 (规格合规 + 代码质量)
  - 更少的人工干预, 更快的迭代

系统调试工作流

Systematic Debugging 四阶段:

Phase 1: 根因调查 (Root Cause Investigation)
  ├─ 读取完整错误信息
  ├─ 复现问题 (确认非随机)
  ├─ 检查最近变更 (git log / diff)
  └─ 在组件边界添加诊断

Phase 2: 模式分析 (Pattern Analysis)
  ├─ 找到正常工作的类似场景
  ├─ 对比正常与异常场景的差异
  └─ 理解依赖关系

Phase 3: 假设与测试 (Hypothesis & Test)
  ├─ 形成单一假设: "我认为X是根因,因为Y"
  ├─ 最小改动测试假设
  └─ 3次以上修复失败 → 质疑架构假设

Phase 4: 实现 (Implementation)
  ├─ 先写失败回归测试
  ├─ 最小化修复
  └─ 验证修复 + 无回归

TDD 红-绿-重构

循环:
  RED → 验证RED失败 → GREEN → 验证GREEN通过 → REFACTOR → 回到RED

关键约束:
  1. 未写失败测试前, 不能写生产代码
  2. 确认测试因预期原因失败 (非语法错误等)
  3. 写最简单的代码让测试通过 (不过度设计)
  4. 重构时保持测试全部绿色
  5. 每次只一个循环, 小步快跑

多Agent协作模式

模式1: 并行派发 (Parallel Dispatching)
  适用: 多个独立任务
  Agent1 ─┐
  Agent2 ─┼─ 同时启动
  Agent3 ─┘

模式2: 管线式 (Pipeline)
  适用: 依赖链任务
  Agent1 → Agent2 → Agent3

模式3: Generator-Evaluator
  适用: 创意/生产内容
  Generator创建 → Evaluator评审 → Generator改进

模式4: 分层审阅 (Layered Review)
  适用: 高质量要求
  规格审阅 → 代码审阅 → 安全审阅 → 性能审阅

提示词工程与缓存

Prompt Caching (提示词缓存)

缓存的层级:
  ┌──────────────┐
  │ System Prompt │ ← 始终缓存 (~4000 tokens)
  ├──────────────┤
  │   Messages    │ ← 前缀匹配缓存
  ├──────────────┤
  │  Tool Results │ ← 相同调用可缓存
  └──────────────┘

缓存命中策略:
  Cache Breakpoints 设置:
  - 在system prompt末尾
  - 在每轮对话开始
  - 在tool定义之后

成本节省:
  Cache Write:  25% of base price
  Cache Read:   10% of base price
  总节省可达:   90%

提示词优化原则

原则1: 结构化提示
  ✅ 使用明确的标题和分段
  ✅ 用代码块标注格式要求
  ❌ 大段连续文字

原则2: 具体 > 抽象
  ✅ "方法名用动词开头, 如getUserByEmail"
  ❌ "写个干净的代码"

原则3: 示例驱动
  ✅ 提供期望的输入输出示例
  ✅ 展示正确和错误的做法

原则4: 约束前置
  ✅ 把必须遵守的规则放在最前面
  ❌ 把约束埋在长文本中间

原则5: 分步指令
  ✅ "1. 先检查依赖 2. 再修改代码 3. 最后验证"
  ❌ "帮我改好这个功能"

Extended Thinking (扩展思考)

配置方法:
  // settings.json
  {
    "enableExtendedThinking": true
  }

  // 或命令行
  claude --enable-extended-thinking

作用:
  - 允许模型在执行复杂推理时使用扩展思考
  - 不会在每次回复中都使用 (自动判断)
  - 适用于架构设计、复杂调试、算法优化

安全与权限模型

权限层级

Level 0: 始终允许 (无需批准)
  └─ Read, Glob, Grep, AskUserQuestion, Task (内部调用)

Level 1: 首次批准后记住 (项目级)
  └─ Bash(特定命令), Write(特定目录), WebFetch

Level 2: 每次询问
  └─ Bash(通用), Write(新文件), Edit(全项目)

Level 3: 始终拒绝
  └─ Bash(危险命令), 特定文件路径

权限模式

default:          标准权限, 大部分操作需确认
acceptEdits:      自动接受文件编辑 (仍需要Bash批准)
bypassPermissions: 跳过所有权限检查 (需显式启用)
plan:             计划模式, 只允许探索性操作

安全最佳实践

1. 项目隔离
   - 每个项目独立的 .claude/ 目录
   - 不同项目不同权限配置

2. 密钥管理
   - 绝不将API密钥写在 CLAUDE.md 中
   - 使用环境变量注入敏感信息
   - .claude/ 目录加入 .gitignore

3. 审计追踪
   - 启用 PostToolUse hook 记录所有操作
   - 定期使用 security-scan 扫描配置

4. 依赖安全检查
   - MCP服务器来源验证
   - Skill来源验证
   - 插件市场URL验证

5. 自动化安全
   - CI/CD集成 security-scan
   - 预提交hook检查密钥泄露

性能优化实战

启动速度优化

优化项:
  ✅ MCP服务器延迟加载 (只加载启用项)
  ✅ Skills按需激活 (非全局加载)
  ✅ 精简CLAUDE.md (移除未使用的规则)
  ✅ 使用 --resume 恢复会话 (跳过初始化)

  启动时间分解:
    CLI启动：         < 1s
    项目初始化:       1-3s
    MCP连接:          每个服务器 1-5s
    API首次响应:      2-5s

响应速度优化

策略1: 选择合适的模型
  - 简单任务用 Haiku (响应更快)
  - 只在必要时用 Opus (复杂推理)

策略2: 控制上下文大小
  - 及时 /compact
  - 避免加载不必要的文件
  - 限制Skill激活数量

策略3: 并行工具调用
  - Claude Code自动并行化独立的工具调用
  - 不需要手动优化

策略4: 使用子Agent
  - 大任务拆分为小Agent
  - 并行派发多个Agent
  - 每个Agent上下文更精简

成本优化

成本构成:
  API调用费用 (按token计费)
  ├─ Input tokens (相对便宜)
  ├─ Output tokens (较贵)
  ├─ Cache write (25% of base)
  └─ Cache read (10% of base)

优化策略:
  1. 启用Prompt Caching (节省90%)
  2. 使用Batch API (非实时场景, 节省50%)
  3. 任务分级 (简单→Haiku, 中等→Sonnet, 复杂→Opus)
  4. 精简System Prompt (减少固定开销)
  5. 控制会话长度 (及时压缩)

插件与扩展系统

Plugin系统架构

插件市场:
  Official:  https://marketplace.anthropic.com (官方, 需网络)
  Community: 用户自定义市场源

插件类型:
  ├─ Skills (技能):   领域专用指令集
  ├─ MCP Servers:    工具/资源服务
  ├─ Hooks:          生命周期钩子
  └─ Themes:         界面主题

Plugin管理命令

bash

# 添加市场
claude plugin marketplace add <url>
claude plugin marketplace add anthropics/skills

# 安装插件
claude plugin install <plugin-name>

# 列出插件
claude plugin list

# 移除插件
claude plugin uninstall <plugin-name>

# 更新插件
claude plugin update

扩展开发模式

3种扩展开发方法:

1. 创建自定义Skill
   → 写 SKILL.md 文档
   → 定义触发条件和规则
   → 通过 skills add 安装

2. 构建MCP服务器
   → 选择语言 (Python FastMCP / TypeScript MCP SDK)
   → 定义工具/资源接口
   → 注册到 mcp.json

3. 配置自定义Hooks
   → 在 settings.json 中添加hook
   → 定义触发事件和命令
   → 测试hook行为

CLAUDE.md 配置文件详解

文件发现机制

CLAUDE.md 搜索顺序 (递归向上):
  当前目录 → 父目录 → 父目录的父目录 → ...

  找到的所有 CLAUDE.md 按以下规则合并:
  - 最近的优先 (覆盖远端)
  - 子目录优先级高于父目录
  - 允许显式 import 其他CLAUDE.md

CLAUDE.md 结构指南

markdown

# CLAUDE.md 最佳实践

## 项目概述
<!-- 简要描述项目是什么, 让AI快速理解上下文 -->

## 技术栈
<!-- 列出使用的语言、框架、关键依赖 -->

## 代码规范
<!-- 编码风格、命名约定、项目特定规则 -->

## 目录结构
<!-- 关键目录的用途说明 -->

## 工作流约定
<!-- 开发流程、分支策略、审阅要求 -->

## 约束条件
<!-- 绝对不能做的事情, 硬性限制 -->

## 外部引用
<!-- 引用其他指令文件 -->
<!-- @include: ~/.claude/rules/security.md -->

## 环境配置
<!-- 必要的环境变量、工具版本 -->

高级CLAUDE.md技巧

技巧1: 条件指令
  使用HTML注释标记条件激活:
  <!-- docx-active --> 只在有docx任务时生效的指令

技巧2: 模块化引用
  不要把一切写在单个CLAUDE.md:
  主文件: 项目概述 + 核心规则
  子文件: ~/.claude/rules/python.md (按需引用)

技巧3: Evolution Memory
  <!-- evolver-evolution-memory -->
  自动管理的学习记忆, 不要手动编辑

技巧4: MCP指令
  在CLAUDE.md中指导AI如何使用MCP工具:
  "查询数据库时使用 mcp__postgres__query 工具"

技巧5: Skill触发指令
  明确告诉AI什么时候应该激活技能:
  "实现新功能前, 必须先走 brainstorming 流程"

总结: Claude Code 高级技巧原则

十条黄金法则

1.  Plan First, Code Later
    复杂任务先设计再编码, Plan Mode是你的朋友

2.  Small, Isolated Agents
    用子Agent隔离上下文, 避免污染和群体思维

3.  Parallel When Independent
    独立任务并行派发, 最大化效率

4.  Verify Before Claiming
    声称完成前必须运行验证命令, 不做口嗨

5.  TDD Is Non-Negotiable
    RED → GREEN → REFACTOR, 铁律不破

6.  Skills Over Ad-Hoc Instructions
    用技能系统持久化模式, 不是临时口头指令

7.  Least Privilege Always
    只给AI完成当前任务所需的最小权限

8.  Context Is Your Budget
    上下文窗口有限, 精简要加载的内容

9.  Hooks For Automation
    用Hooks自动化重复操作, 减少人工干预

10. CLAUDE.md Is Your Co-pilot's Manual
    项目指令文件就是导航手册, 写得越好AI越强

技能与工作流速查

功能开发:    brainstorming → writing-plans → subagent-driven-development
Bug修复:     systematic-debugging → test-driven-development → verification
代码审阅:    requesting-code-review → receiving-code-review
前端页面:    frontend-design → web-design-guidelines → browser-qa
API设计:     api-design → backend-patterns → security-review
数据库:      postgres-patterns → database-migrations
部署:        docker-patterns → deployment-patterns
安全:        security-review → security-scan
AI工程:      claude-api → cost-aware-llm-pipeline → agent-eval
文档:        brand-voice → article-writing → doc/pdf

本文档基于 Claude Code 2.x 版本编写, 部分功能可能随版本更新而变化。更多信息请参考官方文档: https://docs.anthropic.com

Claude Code 高级技巧与组件架构完全指南 ​

目录 ​

架构总览 ​

整体架构图 ​

关键设计原则 ​

核心组件详解 ​

1. Session Manager (会话管理器) ​

2. Prompt Composer (提示词组装器) ​

3. Tool Registry (工具注册表) ​

4. Model Router (模型路由器) ​

子Agent系统 ​

架构设计 ​

Agent类型全览 ​

并行Agent派发模式 ​

后台Agent模式 ​

子Agent上下文管理 ​

Skills技能系统 ​

技能架构 ​

技能三大类型 ​

技能优先级 ​

技能管理命令 ​

自定义技能开发 ​

Hooks钩子系统 ​

Hooks架构 ​

Hook配置 ​

Hooks环境变量 ​

Hooks常见应用场景 ​

Evolution Memory (Evolver) ​

MCP协议集成 ​

MCP架构 ​

MCP配置 (mcp.json) ​

MCP上下文预算影响 ​

MCP服务器安全 ​

上下文窗口管理 ​

上下文组成结构 ​

上下文优化策略 ​

Token预算感知 ​

工具系统深度解析 ​

Task 工具 (子Agent编排) ​

Bash 工具 (终端执行) ​

文件操作工具 ​

CLI命令与高级配置 ​

命令总览 ​

高级REPL命令 ​

settings.json 完整配置参考 ​

高级工作流模式 ​

Plan Mode (计划模式) ​

Subagent-Driven Development (子Agent驱动开发) ​

系统调试工作流 ​

TDD 红-绿-重构 ​

多Agent协作模式 ​

提示词工程与缓存 ​

Prompt Caching (提示词缓存) ​

提示词优化原则 ​

Extended Thinking (扩展思考) ​

安全与权限模型 ​

权限层级 ​

权限模式 ​

安全最佳实践 ​

性能优化实战 ​

启动速度优化 ​

响应速度优化 ​

成本优化 ​

插件与扩展系统 ​

Plugin系统架构 ​

Plugin管理命令 ​

扩展开发模式 ​

CLAUDE.md 配置文件详解 ​

文件发现机制 ​

CLAUDE.md 结构指南 ​

高级CLAUDE.md技巧 ​

总结: Claude Code 高级技巧原则 ​

十条黄金法则 ​

技能与工作流速查 ​

Claude Code 高级技巧与组件架构完全指南

目录

架构总览

整体架构图

关键设计原则

核心组件详解

1. Session Manager (会话管理器)

2. Prompt Composer (提示词组装器)

3. Tool Registry (工具注册表)

4. Model Router (模型路由器)

子Agent系统

架构设计

Agent类型全览

并行Agent派发模式

后台Agent模式

子Agent上下文管理

Skills技能系统

技能架构

技能三大类型

技能优先级

技能管理命令

自定义技能开发

Hooks钩子系统

Hooks架构

Hook配置

Hooks环境变量

Hooks常见应用场景

Evolution Memory (Evolver)

MCP协议集成

MCP架构

MCP配置 (mcp.json)

MCP上下文预算影响

MCP服务器安全

上下文窗口管理

上下文组成结构

上下文优化策略

Token预算感知

工具系统深度解析

Task 工具 (子Agent编排)

Bash 工具 (终端执行)

文件操作工具

CLI命令与高级配置

命令总览

高级REPL命令

settings.json 完整配置参考

高级工作流模式

Plan Mode (计划模式)

Subagent-Driven Development (子Agent驱动开发)

系统调试工作流

TDD 红-绿-重构

多Agent协作模式

提示词工程与缓存

Prompt Caching (提示词缓存)

提示词优化原则

Extended Thinking (扩展思考)

安全与权限模型

权限层级

权限模式

安全最佳实践

性能优化实战

启动速度优化

响应速度优化

成本优化

插件与扩展系统

Plugin系统架构

Plugin管理命令

扩展开发模式

CLAUDE.md 配置文件详解

文件发现机制

CLAUDE.md 结构指南

高级CLAUDE.md技巧

总结: Claude Code 高级技巧原则

十条黄金法则

技能与工作流速查